<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Save : DataMapper ORM - User Guide</title>

<link rel="shortcut icon" type="image/png" href="../images/favicon.png" />
<link rel="stylesheet" type="text/css" media="all" href="../css/userguide.css" />
<link rel="alternate" type="application/rss+xml" title="Datamapper ORM Updates Feed" href="/rss.xml" />

<meta http-equiv="expires" content="-1" />
<meta http-equiv= 'pragma' content="no-cache" />
<meta name="robots" content="all" />

</head>

<body>

<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"></div></div>
<div id="nav2"><a name="top">&nbsp;</a><a id="nav_toggle" href="#"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>DataMapper ORM</h1></td>
<td id="breadcrumb_right"><a href="toc.html">Table of Contents Page</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->

<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="/">Datamapper ORM Home</a> &nbsp;&#8250;&nbsp;
<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
Save
</td>
</tr>

</table>
<!-- END BREADCRUMB -->

<br clear="all" />


<!-- START CONTENT -->
<div id="content">


<h1>Save</h1>

<p>There are a number of ways to run Save and its effect will be different depending on the condition of the object you run it on, and whether you pass in a parameter.</p>

<h2 id="Save.New">Save on a New Object</h2>
<p>Running Save on a new object, one without an ID, will see a new record created for it its relevant Database table.  After saving, it will automatically populate itself with its new data, such as its ID and any changes its properties had after validation (such as an encrypted password).</p>
<pre>
<samp>// Create new User
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();

</kbd><samp>// Enter values into required fields
</samp><var>$u</var><kbd>-&gt;</kbd><var>username </var><kbd>= </kbd><dfn>"foo"</dfn><kbd>;
</kbd><var>$u</var><kbd>-&gt;</kbd><var>password </var><kbd>= </kbd><dfn>"bar"</dfn><kbd>;
</kbd><var>$u</var><kbd>-&gt;</kbd><var>email </var><kbd>= </kbd><dfn>"foo@bar.com"</dfn><kbd>;

</kbd><samp>// Save new user
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>save</u></var><kbd>();</kbd>
</pre>

<p>The new user <b>foo</b> will now have an ID and an encrypted password (as well as a salt for use later on when he logs in).</p>

<h2 id="Save.Existing">Save on an Existing Object</h2>
<p>Running Save on an existing object will update its corresponding record in the database.</p>
<pre>
<samp>// Get user foo
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'username'</dfn><kbd>, </kbd><dfn>'foo'</dfn><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();

</kbd><samp>// Change the email
</samp><var>$u</var><kbd>-&gt;</kbd><var>email </var><kbd>= </kbd><dfn>"baz@qux.com"</dfn><kbd>;

</kbd><samp>// Save changes to existing user
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>save</u></var><kbd>();</kbd>
</pre>

<p>As the only change is the email, the email will be updated.</p>

<h2 id="Save.Existing.As.New">Saving new objects with an existing ID</h2>
<p>By default, DataMapper uses the existence of the <strong>id</strong> field to determine whether an object exists or not.  If the object exists, it is <b>UPDATE</b>d, otherwise it is <b>INSERT</b>ed.</p>
<p>This can cause a problem when importing new data into the system, as the data cannot be inserted with known <strong>id</strong>.  To get around this, you can use the <var><u>save_as_new</u></var> method, which forces DataMapper to save the object as if it was new, but inserts the ID as well.</p>
<p>You might also choose to integrate this with the <var><u>skip_validation</u></var> method below.</p>
<p class="important"><strong><em>Warning:</em></strong> If the id of the object being saved is already in use in the database, this will cause a database error.</p>
<div class="note">
	<p><strong><em>Note:</em></strong> If the item being saved has an id greater than the next automatic id value, you may have to update your <a href="http://dev.mysql.com/doc/refman/5.0/en/example-auto-increment.html">auto_increment</a> or <a href="http://www.postgresql.org/docs/8.3/static/sql-altersequence.html">serial</a> for the <b>id</b> column yourself.</p>
	<p>Failure to do this will throw an error the next time an object is saved.  (For some databases, auto_increment may be corrected automatically.)  An example is given below.</p>
</div>
<h3>Example</h3>
<pre>
<var>$user </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$user</var><kbd>-&gt;</kbd><var>id </var><kbd>= </kbd><var>1</var><kbd>;
</kbd><var>$user</var><kbd>-&gt;</kbd><var>name </var><kbd>= </kbd><dfn>'Admin'</dfn><kbd>;
</kbd><var>$user</var><kbd>-&gt;</kbd><var>password </var><kbd>= </kbd><dfn>'password'</dfn><kbd>;
</kbd><var>$success </var><kbd>= </kbd><var>$user</var><kbd>-&gt;</kbd><var><u>save_as_new</u></var><kbd>();
</kbd><samp>// Update MySQL AUTO_INCREMENT:
</samp><var>$user</var><kbd>-&gt;</kbd><var>db</var><kbd>-&gt;</kbd><var><u>query</u></var><kbd>(</kbd><dfn>'ALTER TABLE `users` AUTO_INCREMENT = ' </dfn><kbd>. (</kbd><var>$user</var><kbd>-&gt;</kbd><var>id</var><kbd>+</kbd><var>1</var><kbd>) .</kbd><dfn>';'</dfn><kbd>);
</kbd><samp>// Update PostGreSQL SERIAL:
</samp><var>$user</var><kbd>-&gt;</kbd><var>db</var><kbd>-&gt;</kbd><var><u>query</u></var><kbd>(</kbd><dfn>'ALTER SEQUENCE users_id_seq RESTART WITH ' </dfn><kbd>. (</kbd><var>$user</var><kbd>-&gt;</kbd><var>id</var><kbd>+</kbd><var>1</var><kbd>) . </kbd><dfn>';'</dfn><kbd>);</kbd>
</pre>

<h2 id="Skip.Validation">Skipping Validation</h2>
<p>Occasionally you may want to force a save that skips validation.  This might be, for example, for adminstrative purposes.  To easily do this, call <var><u>skip_validation</u></var> before calling <var><u>save</u></var>.</p>
<p>To re-enable validation, either call <var><u>get</u></var>, <var><u>save</u></var>, or <var><u>skip_validation</u></var><kbd>(</kbd> <dfn>FALSE</dfn> <kbd>)</kbd> on the <var>$object</var>.</p>

<h3>Example</h3>
<pre>
<samp>// set some invalid fields
</samp><var>$user</var><kbd>-&gt;</kbd><var>email </var><kbd>= </kbd><dfn>''</dfn><kbd>;
</kbd><var>$user</var><kbd>-&gt;</kbd><var>password </var><kbd>= </kbd><dfn>''</dfn><kbd>;

</kbd><samp>// save without validating
</samp><var>$success </var><kbd>= </kbd><var>$user</var><kbd>-&gt;</kbd><var><u>skip_validation</u></var><kbd>()-&gt;</kbd><var><u>save</u></var><kbd>();
if(</kbd><var>$success</var><kbd>) </kbd><samp>// ...</samp>
</pre>

<p>As long as the database allows the fields, the object will be saved.  Remember that database rules can still prevent the fields from being saved, and you might see database errors when saving this way.</p>

<h2 id="Save.Failed">Check for failed validation</h2>

<p>When you use validation on the object, validation rules are run before attempting to save the contents of the object.</p>

<h3>Example</h3>
<pre>
<samp>// set some invalid fields
</samp><var>$user</var><kbd>-&gt;</kbd><var>email </var><kbd>= </kbd><dfn>''</dfn><kbd>;
</kbd><var>$user</var><kbd>-&gt;</kbd><var>password </var><kbd>= </kbd><dfn>''</dfn><kbd>;

</kbd><samp>// save
</samp><var>$success </var><kbd>= </kbd><var>$user</var><kbd>-&gt;</kbd><var><u>save</u></var><kbd>();
if(</kbd>! <var>$success</var><kbd>)
{</kbd>
    <samp>// did validation fail?</samp>
    <kbd>if (</kbd> <var>$user->valid</var> <kbd>)
    {</kbd>
         <samp>// insert or update failure</samp>
    <kbd>} else {</kbd>
         <samp>// validation failure</samp>
    <kbd>}</kbd>
<kbd>}</kbd>
</pre>

<h2 id="Relationship">Save a Simple Relationship</h2>

<p>It's easy to save the relationships your objects have with each other, and there are a few ways of doing it.</p>

<p class="important"><strong><em>Important:</em></strong>&nbsp; When saving a relationship on an object, the object itself is also saved if it has changed.</p>

<h3>Save a Single Relation</h3>

<p>To save a relation, you pass the object you want to relate to, into your current object.</p>
<pre>
<samp>// Get user foo
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'username'</dfn><kbd>, </kbd><dfn>'foo'</dfn><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();

</kbd><samp>// Get country object for Australia
</samp><var>$c </var><kbd>= new </kbd><var>Country</var><kbd>();
</kbd><var>$c</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'name'</dfn><kbd>, </kbd><dfn>'Australia'</dfn><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();

</kbd><samp>// Relate user foo to country Australia
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>save</u></var><kbd>(</kbd><var>$c</var><kbd>);</kbd>
</pre>

<h3>Save Multiple Relations</h3>

<p>To save multiple relations, you pass an object's all property or an array of objects.</p>
<pre>
<samp>// Get user foo
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'username'</dfn><kbd>, </kbd><dfn>'foo'</dfn><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();

</kbd><samp>// Get country object for Australia
</samp><var>$c </var><kbd>= new </kbd><var>Country</var><kbd>();
</kbd><var>$c</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'name'</dfn><kbd>, </kbd><dfn>'Australia'</dfn><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();

</kbd><samp>// Get a number of books from the year 2000
</samp><var>$b </var><kbd>= new </kbd><var>Book</var><kbd>();
</kbd><var>$b</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'year'</dfn><kbd>, </kbd><var>2000</var><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();

</kbd><samp>// Get a movie with ID of 5
</samp><var>$m </var><kbd>= new </kbd><var>Movie</var><kbd>();
</kbd><var>$m</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'id'</dfn><kbd>, </kbd><var>5</var><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();

</kbd><samp>// Relate user foo to all the books
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>save</u></var><kbd>(</kbd><var>$b</var><kbd>-&gt;</kbd><var><i>all</i></var><kbd>);

</kbd><samp>// Or we could pass everything in one go (it's ok to have a mix of single objects and all lists from objects)
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>save</u></var><kbd>(array(</kbd><var>$c</var><kbd>, </kbd><var>$b</var><kbd>-&gt;</kbd><var><i>all</i></var><kbd>, </kbd><var>$m</var><kbd>));</kbd>
</pre>

<h3>Save a New object and its Relations in a single call</h3>

<p>It is important to note that you can save both an object's data and relationships with a single save call.  For example, you could save a new object and its relationships all in one go like this:</p>
<pre>
<samp>// Create new User
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();

</kbd><samp>// Enter values into required fields
</samp><var>$u</var><kbd>-&gt;</kbd><var>username </var><kbd>= </kbd><dfn>"foo"</dfn><kbd>;
</kbd><var>$u</var><kbd>-&gt;</kbd><var>password </var><kbd>= </kbd><dfn>"bar"</dfn><kbd>;
</kbd><var>$u</var><kbd>-&gt;</kbd><var>email </var><kbd>= </kbd><dfn>"foo@bar.com"</dfn><kbd>;

</kbd><samp>// Get country object for Australia
</samp><var>$c </var><kbd>= new </kbd><var>Country</var><kbd>();
</kbd><var>$c</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'name'</dfn><kbd>, </kbd><dfn>'Australia'</dfn><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();

</kbd><samp>// Save new user and also save a relationship to the country
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>save</u></var><kbd>(</kbd><var>$c</var><kbd>);</kbd>
</pre>

<h3>Save an Existing object and its Relations in a single call</h3>

<p>In the same way, you can update an existing records data as well as its relationships with a single save call.</p>
<pre>
<samp>// Get user foo
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'username'</dfn><kbd>, </kbd><dfn>'foo'</dfn><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();

</kbd><samp>// Change the email
</samp><var>$u</var><kbd>-&gt;</kbd><var>email </var><kbd>= </kbd><dfn>"baz@qux.com"</dfn><kbd>;

</kbd><samp>// Get country object for United States
</samp><var>$c </var><kbd>= new </kbd><var>Country</var><kbd>();
</kbd><var>$c</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'name'</dfn><kbd>, </kbd><dfn>'United States'</dfn><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();

</kbd><samp>// Update email and update the relationship to country United States
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>save</u></var><kbd>(</kbd><var>$c</var><kbd>);</kbd>
</pre>

<p>&nbsp;</p>
<h2 id="Advanced">Save an Advanced Relationship</h2>

<p>The difference between saving a normal relationship and an advanced one is that you need to specify which <var><s>relationship key</s></var> to save the object to.</p>

<p>This can be handled in several ways</p>

<h3>$object->save_{$relationship_key}( $related )</h3>
<p>Saves a single <dfn>$related</dfn> as a <var><s>$relationship_key</s></var> on <var>$object</var>.</p>
<ul>
	<li><var><s>{$relationship_key}</s></var>: Replace with the relationship key you want to save on.</li>
	<li><dfn>$related</dfn>: The object to save.</li>
</ul>
<pre>
<samp>// Create Post
</samp><var>$post </var><kbd>= new </kbd><var>Post</var><kbd>();
</kbd><samp>// save $user as the creator
</samp><var>$post</var><kbd>-&gt;</kbd><var><u>save</u>_<s>creator</s></var><kbd>(</kbd><dfn>$user</dfn><kbd>);</kbd>
</pre>


<h3>$object->save_{$relationship_key}( $array )</h3>
<p>Saves an <dfn>$array</dfn> of related objects as <var><s>$relationship_key</s></var>s on <var>$object</var>.</p>
<ul>
	<li><var><s>{$relationship_key}</s></var>: Replace with the relationship key you want to save on.</li>
	<li><dfn>$array</dfn>: The objects to save.</li>
</ul>
<pre>
<samp>// Create Post
</samp><var>$post </var><kbd>= new </kbd><var>Post</var><kbd>();
</kbd><samp>// Load in related posts.
</samp><var>$relatedposts </var><kbd>= new </kbd><var>Post</var><kbd>();
</kbd><var>$relatedposts</var><kbd>-&gt;</kbd><var><u>where_in</u></var><kbd>(</kbd><var>$related_ids</var><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();
</kbd><samp>// save related posts
</samp><var>$post</var><kbd>-&gt;</kbd><var><u>save_</u><s>relatedpost</s></var><kbd>(</kbd><var>$relatedposts</var><kbd>-&gt;</kbd><dfn>all</dfn><kbd>);</kbd>
</pre>

<h3>$object->save( $related, $relationship_key )</h3>
<p>Saves one or more <dfn>$related</dfn> as a <var><s>$relationship_key</s></var> on <var>$object</var>.</p>
<ul>
	<li><dfn>$related</dfn>: The object or objects to save.</li>
	<li><var><s>$relationship_key</s></var>: The relationship key you want to save on.</li>
</ul>
<pre>
<samp>// Create Post
</samp><var>$post </var><kbd>= new </kbd><var>Post</var><kbd>();
</kbd><samp>// save $user as the creator
</samp><var>$post</var><kbd>-&gt;</kbd><var><u>save</u></var><kbd>(</kbd><dfn>$user</dfn><kbd>, </kbd><var><s>'creator'</s></var><kbd>);</kbd>
</pre>

<h3>Saving a variety of objects</h3>
<p>Finally, you can use associative arrays to save a variety of different relationshups</p>
<pre>
<samp>// Create Post
</samp><var>$post </var><kbd>= new </kbd><var>Post</var><kbd>();

</kbd><samp>// save $user as the creator and editor, and save related posts.
</samp><var>$post</var><kbd>-&gt;</kbd><var><u>save</u></var><kbd>(
    array(
        </kbd><var><s>'creator'</s></var> <kbd>=&gt; </kbd><dfn>$user</dfn><kbd>,
        </kbd><var><s>'editor'</s></var> <kbd>=&gt; </kbd><dfn>$user</dfn><kbd>,
        </kbd><var><s>'relatedpost'</s></var> <kbd>=&gt; </kbd><var>$relatedposts</var><kbd>-&gt;</kbd><dfn>all</dfn><var>
    </var><kbd>)
);</kbd>
</pre>



</div>
<!-- END CONTENT -->


<div id="footer">
<p>
<span id="footer_previous">Previous Topic:&nbsp;&nbsp;<a href=""></a>
&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;</span>
<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="../index.html">User Guide Home</a>
<span id="footer_next">&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Next Topic:&nbsp;&nbsp;<a href=""></a></span>
</p>
<div id="copyrights">
<p><a href="/">Datamapper ORM</a> &nbsp;&middot;&nbsp; Copyright &copy; 2010-2011 &nbsp;&middot;&nbsp; Harro "WanWizard" Verton</p>
<p><a href="license.html">Other License Information</a></p>
</div>
</div>

<script type="text/javascript" src="../js/mootools.js"></script>
<script type="text/javascript" src="../js/menu.js"></script>
<script type="text/javascript">
<!--
	window.addEvent('domready', function() {

		// Create Menu
		var menu = new Menu({
			basepath: '../',
			pagespath: ''
		});

	});
//-->
</script>
</body>
</html>
